BlueRequests API Reference #

Comprehensive REST API documentation for BlueRequests change management platform. Use these APIs to integrate BlueRequests with your existing tools and workflows.

Getting Started #

Authentication #

BlueRequests API uses Bearer token authentication. Include your API token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     https://api.bluereq.company.com/v1/requests

Base URL #

Production: https://api.bluereq.company.com/v1
Staging: https://api-staging.bluereq.company.com/v1

Rate Limiting #

Rate Limit: 1000 requests per hour per API key
Burst Limit: 100 requests per minute
Headers: Rate limit information is returned in response headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Change Requests API #

List Requests #

Get a paginated list of change requests.

GET /v1/requests

Query Parameters #

Parameter	Type	Description	Default
`page`	integer	Page number	1
`limit`	integer	Items per page (max 100)	20
`status`	string	Filter by status	all
`priority`	string	Filter by priority	all
`assignee`	string	Filter by assignee ID	all
`created_after`	string	ISO 8601 date	none
`created_before`	string	ISO 8601 date	none

Example Request #

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.bluereq.company.com/v1/requests?status=approved&limit=50"

Example Response #

{
  "requests": [
    {
      "id": "req_123456",
      "title": "Update User Authentication System",
      "description": "Implement multi-factor authentication",
      "status": "approved",
      "priority": "high",
      "type": "enhancement",
      "creator": {
        "id": "user_789",
        "name": "John Doe",
        "email": "john.doe@company.com"
      },
      "assignee": {
        "id": "user_456",
        "name": "Jane Smith",
        "email": "jane.smith@company.com"
      },
      "created_at": "2023-12-01T10:00:00Z",
      "updated_at": "2023-12-02T14:30:00Z",
      "due_date": "2023-12-15T00:00:00Z",
      "estimated_hours": 40,
      "tags": ["security", "authentication"],
      "project": {
        "id": "proj_001",
        "name": "Security Enhancement Project"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Create Request #

Create a new change request.

POST /v1/requests

Request Body #

{
  "title": "New Feature Implementation",
  "description": "Detailed description of the change request",
  "priority": "medium",
  "type": "feature",
  "assignee_id": "user_456",
  "due_date": "2023-12-31T23:59:59Z",
  "estimated_hours": 20,
  "tags": ["feature", "ui"],
  "project_id": "proj_001",
  "custom_fields": {
    "business_impact": "medium",
    "affected_systems": ["SAP", "CRM"]
  }
}

Example Response #

{
  "id": "req_123457",
  "title": "New Feature Implementation",
  "status": "draft",
  "created_at": "2023-12-01T15:00:00Z",
  "request_number": "CR-2023-001234"
}

Get Request #

Retrieve a specific change request by ID.

GET /v1/requests/{request_id}

Example Response #

{
  "id": "req_123456",
  "request_number": "CR-2023-001233",
  "title": "Update User Authentication System",
  "description": "Implement multi-factor authentication for enhanced security",
  "status": "in_progress",
  "priority": "high",
  "type": "enhancement",
  "creator": {
    "id": "user_789",
    "name": "John Doe",
    "email": "john.doe@company.com"
  },
  "assignee": {
    "id": "user_456",
    "name": "Jane Smith",
    "email": "jane.smith@company.com"
  },
  "approvers": [
    {
      "id": "user_123",
      "name": "Mike Johnson",
      "email": "mike.johnson@company.com",
      "status": "approved",
      "approved_at": "2023-12-02T09:30:00Z"
    }
  ],
  "comments": [
    {
      "id": "comment_001",
      "author": {
        "id": "user_456",
        "name": "Jane Smith"
      },
      "content": "Started implementation work",
      "created_at": "2023-12-02T14:30:00Z"
    }
  ],
  "attachments": [
    {
      "id": "attach_001",
      "filename": "requirements.pdf",
      "size": 1024576,
      "url": "https://files.bluereq.company.com/attach_001"
    }
  ],
  "timeline": [
    {
      "event": "created",
      "timestamp": "2023-12-01T10:00:00Z",
      "user": "John Doe"
    },
    {
      "event": "status_changed",
      "timestamp": "2023-12-02T09:30:00Z",
      "user": "Mike Johnson",
      "details": {
        "from": "pending_approval",
        "to": "approved"
      }
    }
  ]
}

Update Request #

Update an existing change request.

PUT /v1/requests/{request_id}

Request Body #

{
  "title": "Updated Request Title",
  "description": "Updated description",
  "priority": "low",
  "status": "in_progress",
  "assignee_id": "user_789",
  "estimated_hours": 30
}

Delete Request #

Delete a change request (only for drafts).

DELETE /v1/requests/{request_id}

Approval Workflows API #

Get Workflow #

Retrieve workflow configuration for a request.

GET /v1/requests/{request_id}/workflow

Example Response #

{
  "workflow_id": "wf_001",
  "name": "Standard Approval Workflow",
  "steps": [
    {
      "id": "step_001",
      "name": "Technical Review",
      "type": "approval",
      "required_approvers": 1,
      "approvers": [
        {
          "id": "user_123",
          "name": "Tech Lead",
          "status": "pending"
        }
      ]
    },
    {
      "id": "step_002",
      "name": "Business Approval",
      "type": "approval",
      "required_approvers": 1,
      "approvers": [
        {
          "id": "user_456",
          "name": "Business Owner",
          "status": "not_reached"
        }
      ]
    }
  ],
  "current_step": "step_001"
}

Submit for Approval #

Submit a request for approval workflow.

POST /v1/requests/{request_id}/submit

Approve/Reject #

Approve or reject a request in the current workflow step.

POST /v1/requests/{request_id}/approve

{
  "action": "approve",
  "comment": "Looks good, approved for implementation"
}

POST /v1/requests/{request_id}/reject

{
  "action": "reject",
  "comment": "Needs more detailed requirements",
  "send_back_to": "creator"
}

Projects API #

List Projects #

GET /v1/projects

Example Response #

{
  "projects": [
    {
      "id": "proj_001",
      "name": "Security Enhancement Project",
      "description": "Improve overall system security",
      "status": "active",
      "start_date": "2023-11-01T00:00:00Z",
      "end_date": "2024-03-31T23:59:59Z",
      "manager": {
        "id": "user_123",
        "name": "Project Manager"
      },
      "team_members": [
        {
          "id": "user_456",
          "name": "Developer 1",
          "role": "developer"
        },
        {
          "id": "user_789",
          "name": "Developer 2",
          "role": "developer"
        }
      ],
      "request_count": 25,
      "completed_requests": 15
    }
  ]
}

Create Project #

POST /v1/projects

{
  "name": "New Project",
  "description": "Project description",
  "start_date": "2024-01-01T00:00:00Z",
  "end_date": "2024-06-30T23:59:59Z",
  "manager_id": "user_123",
  "team_member_ids": ["user_456", "user_789"]
}

Users API #

List Users #

GET /v1/users

Query Parameters #

Parameter	Type	Description
`role`	string	Filter by role
`team`	string	Filter by team
`active`	boolean	Filter by active status

Example Response #

{
  "users": [
    {
      "id": "user_123",
      "name": "John Doe",
      "email": "john.doe@company.com",
      "role": "developer",
      "team": "Backend Team",
      "active": true,
      "last_login": "2023-12-01T14:30:00Z",
      "permissions": [
        "create_request",
        "approve_technical",
        "view_all_projects"
      ]
    }
  ]
}

Get User Profile #

GET /v1/users/{user_id}

Update User #

PUT /v1/users/{user_id}

Comments API #

Add Comment #

Add a comment to a change request.

POST /v1/requests/{request_id}/comments

{
  "content": "This is a comment on the request",
  "mentions": ["user_456", "user_789"],
  "attachments": ["file_001"]
}

List Comments #

GET /v1/requests/{request_id}/comments

Update Comment #

PUT /v1/comments/{comment_id}

Delete Comment #

DELETE /v1/comments/{comment_id}

Notifications API #

List Notifications #

GET /v1/notifications

Query Parameters #

Parameter	Type	Description
`read`	boolean	Filter by read status
`type`	string	Filter by notification type

Example Response #

{
  "notifications": [
    {
      "id": "notif_001",
      "type": "request_approved",
      "title": "Request Approved",
      "message": "Your request 'Update User Auth' has been approved",
      "read": false,
      "created_at": "2023-12-01T10:00:00Z",
      "related_object": {
        "type": "request",
        "id": "req_123456"
      }
    }
  ]
}

Mark as Read #

PUT /v1/notifications/{notification_id}/read

Mark All as Read #

PUT /v1/notifications/read-all

Reports API #

Get Dashboard Data #

GET /v1/reports/dashboard

Example Response #

{
  "summary": {
    "total_requests": 150,
    "pending_approval": 25,
    "in_progress": 45,
    "completed_this_month": 20
  },
  "charts": {
    "requests_by_status": [
      {"status": "draft", "count": 10},
      {"status": "pending_approval", "count": 25},
      {"status": "approved", "count": 30},
      {"status": "in_progress", "count": 45},
      {"status": "completed", "count": 40}
    ],
    "requests_by_priority": [
      {"priority": "low", "count": 50},
      {"priority": "medium", "count": 70},
      {"priority": "high", "count": 25},
      {"priority": "critical", "count": 5}
    ]
  }
}

Generate Report #

POST /v1/reports/generate

{
  "type": "project_summary",
  "project_id": "proj_001",
  "date_range": {
    "start": "2023-11-01T00:00:00Z",
    "end": "2023-12-31T23:59:59Z"
  },
  "format": "pdf"
}

Webhooks API #

Create Webhook #

POST /v1/webhooks

{
  "url": "https://your-app.com/webhooks/bluereq",
  "events": [
    "request.created",
    "request.approved",
    "request.completed"
  ],
  "secret": "your-webhook-secret"
}

List Webhooks #

GET /v1/webhooks

Update Webhook #

PUT /v1/webhooks/{webhook_id}

Delete Webhook #

DELETE /v1/webhooks/{webhook_id}

Webhook Events #

BlueRequests sends webhook notifications for the following events:

Request Events #

request.created - New request created
request.updated - Request updated
request.submitted - Request submitted for approval
request.approved - Request approved
request.rejected - Request rejected
request.completed - Request completed
request.deleted - Request deleted

Comment Events #

comment.created - New comment added
comment.updated - Comment updated
comment.deleted - Comment deleted

Project Events #

project.created - New project created
project.updated - Project updated
project.completed - Project completed

Example Webhook Payload #

{
  "event": "request.approved",
  "timestamp": "2023-12-01T10:00:00Z",
  "data": {
    "request": {
      "id": "req_123456",
      "title": "Update User Authentication",
      "status": "approved",
      "approver": {
        "id": "user_123",
        "name": "Mike Johnson"
      }
    }
  }
}

Error Responses #

Error Format #

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "title",
        "message": "Title is required"
      }
    ]
  }
}

Common Error Codes #

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API token
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Request validation failed
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`INTERNAL_ERROR`	500	Internal server error

SDK and Libraries #

JavaScript/Node.js #

npm install @bluereq/api-client

const BlueReq = require('@bluereq/api-client');

const client = new BlueReq({
  apiToken: 'your-api-token',
  baseUrl: 'https://api.bluereq.company.com/v1'
});

// Create a request
const request = await client.requests.create({
  title: 'New Feature',
  description: 'Feature description',
  priority: 'medium'
});

// List requests
const requests = await client.requests.list({
  status: 'approved',
  limit: 50
});

Python #

pip install bluereq-api

from bluereq import BlueReqClient

client = BlueReqClient(
    api_token='your-api-token',
    base_url='https://api.bluereq.company.com/v1'
)

# Create a request
request = client.requests.create({
    'title': 'New Feature',
    'description': 'Feature description',
    'priority': 'medium'
})

# List requests
requests = client.requests.list(status='approved', limit=50)

cURL Examples #

See the individual endpoint documentation above for complete cURL examples.

For more information about API usage, rate limits, and best practices, contact our support team or visit the developer portal.