API Documentation¶

Overview¶

The BidScript backend exposes RESTful APIs to interact with various features of the application. The application uses JWT tokens for authentication with selective endpoint protection.

Authentication¶

JWT Authentication¶

Protected endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer {token}

The JWT token should contain user identification information including userID and companyID.

Health Check¶

System Health¶

GET /health

Public endpoint that returns system health status.

Response:

{
  "status": "healthy|degraded",
  "timestamp": "string",
  "version": "string",
  "services": {}
}

Application Status¶

GET /

Public endpoint that returns a simple hello message.

Response:

"Hello World!"

Document Management¶

Upload Document¶

POST /azure/documents/upload

Request:

Content-Type: multipart/form-data
Form Data:
file: File (PDF, DOCX, etc.)
metadata: JSON string (optional)

Response:

{
  "id": "string",
  "filename": "string",
  "contentType": "string",
  "size": "number",
  "url": "string",
  "createdAt": "string"
}

Parse Document¶

POST /azure/documents/parse

Request Body:

{
  "documentId": "string",
  "options": {
    "chunkSize": "number",
    "overlap": "number"
  }
}

Response:

{
  "id": "string",
  "status": "string",
  "chunks": "number",
  "jobId": "string"
}

Get Document¶

GET /azure/documents/{id}

Response:

{
  "id": "string",
  "filename": "string",
  "contentType": "string",
  "size": "number",
  "url": "string",
  "metadata": "object",
  "createdAt": "string",
  "parsedAt": "string"
}

Delete Document¶

DELETE /azure/documents/{id}

Response:

{
  "success": "boolean",
  "message": "string"
}

Chat API¶

Send Message¶

POST /chat

Public endpoint for processing chat messages.

Request Body:

{
  "userID": "string",
  "companyID": "string",
  "conversationUUID": "string",
  "conversationId": "string",
  "message": "string",
  "documents": [
    {
      "name": "string",
      "type": "string",
      "content": "string"
    }
  ]
}

Response:

{
  "response": "string",
  "conversationId": "string",
  "timestamp": "string"
}

CORS Support¶

OPTIONS /chat

Handles preflight requests for CORS support.

## Conversation Management

### Get All Conversations

GET /conversations

Protected endpoint that requires JWT authentication.

Query Parameters:
- `userID`: User identifier (if not in JWT token)

Response:
```json
[
  {
    "id": "string",
    "title": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "userID": "string"
  }
]

Get Conversation by ID¶

GET /conversations/{id}

Protected endpoint that returns a specific conversation.

Response:

{
  "id": "string",
  "title": "string",
  "messages": ["object"],
  "createdAt": "string",
  "updatedAt": "string"
}

Create Conversation¶

POST /conversations

Protected endpoint to create a new conversation.

Request Body:

{
  "title": "string",
  "userID": "string"
}

Delete Conversation¶

DELETE /conversations/{id}

Protected endpoint to delete a conversation.

Response:

{
  "success": "boolean"
}

Document Processing¶

Process Documents¶

POST /api/documents/process

Processes uploaded documents for analysis.

Request Body:

{
  "documents": [
    {
      "name": "string",
      "type": "string",
      "content": "string"
    }
  ]
}

Response:

[
  {
    "documentId": "string",
    "processedChunks": "number",
    "metadata": "object"
  }
]

Notifications¶

Get User Notifications¶

GET /notifications/user/{userId}

Public endpoint to retrieve notifications for a user.

Response:

[
  {
    "id": "string",
    "userId": "string",
    "title": "string",
    "description": "string",
    "type": "string",
    "isRead": "boolean",
    "requiresAction": "boolean",
    "links": [
      {
        "text": "string",
        "path": "string",
        "description": "string"
      }
    ],
    "createdAt": "string"
  }
]

Create Notification¶

POST /notifications

Public endpoint to create a new notification.

Request Body:

{
  "userId": "string",
  "title": "string",
  "description": "string",
  "type": "info|warning|error|success",
  "requiresAction": "boolean",
  "links": [
    {
      "text": "string",
      "path": "string",
      "description": "string"
    }
  ]
}

Mark Notification as Read¶

PATCH /notifications/{id}/read

Public endpoint to mark a notification as read.

Delete Notification¶

DELETE /notifications/{id}

Public endpoint to delete a notification.

Editor API¶

Create Document¶

POST /editor/documents

Request Body:

{
  "title": "string",
  "content": "string",
  "documentType": "string",
  "metadata": "object"
}

Response:

{
  "id": "string",
  "title": "string",
  "documentType": "string",
  "createdAt": "string"
}

Get Document¶

GET /editor/documents/{id}

Response:

{
  "id": "string",
  "title": "string",
  "content": "string",
  "documentType": "string",
  "metadata": "object",
  "createdAt": "string",
  "updatedAt": "string"
}

Update Document¶

PATCH /editor/documents/{id}

Request Body:

{
  "title": "string",
  "content": "string",
  "metadata": "object"
}

Response:

{
  "id": "string",
  "title": "string",
  "updatedAt": "string"
}

Delete Document¶

DELETE /editor/documents/{id}

Response:

{
  "success": "boolean",
  "message": "string"
}

Collaboration API¶

Join Collaboration Session¶

POST /collaboration/join

Request Body:

{
  "documentId": "string",
  "userId": "string",
  "userName": "string"
}

Response:

{
  "sessionId": "string",
  "participants": [
    {
      "userId": "string",
      "userName": "string",
      "connectedAt": "string"
    }
  ]
}

Leave Collaboration Session¶

POST /collaboration/leave

Request Body:

{
  "sessionId": "string",
  "userId": "string"
}

ProjectHub API¶

Process Tender Pack¶

POST /tender-parsing/process

Request Body:

{
  "documentId": "string",
  "options": {
    "extractRequirements": "boolean",
    "identifyDeadlines": "boolean",
    "categoriseContent": "boolean"
  }
}

Response:

{
  "id": "string",
  "status": "string",
  "sections": "number",
  "requirements": "number",
  "jobId": "string"
}

Get Tender Processing Status¶

GET /tender-parsing/status/{jobId}

Response:

{
  "jobId": "string",
  "status": "string",
  "progress": "number",
  "completed": "boolean",
  "error": "string"
}

Error Handling¶

All API endpoints follow a consistent error response format:

{
  "statusCode": "number",
  "timestamp": "string",
  "path": "string",
  "message": "string",
  "error": "string"
}

Common HTTP status codes:

200: Success
201: Created
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
500: Internal Server Error

Rate Limiting¶

API endpoints are subject to rate limiting:

100 requests per minute for authenticated users
10 requests per minute for unauthenticated users

Exceeded rate limits will return a 429 (Too Many Requests) status code.