API Reference - DeployBrief Documentation

API Overview

The DeployBrief API allows you to programmatically generate, retrieve, and manage deployment briefs. All endpoints require authentication via API key.

Base URL:

https://api.deploybrief.com/api

Authentication:

Authorization: Bearer YOUR_API_KEY

See API Authentication for details on creating and managing API keys.

Authentication

All API requests must include an API key in the Authorization header:

curl https://api.deploybrief.com/api/briefs \
  -H "Authorization: Bearer db_1234567890abcdef"

Response Codes

200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

GET /api/briefs

Retrieve a list of deployment briefs for your workspace.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
pageSize	integer	Items per page (default: 20, max: 100)
search	string	Search by pipeline name or build number
pipelineId	integer	Filter by Azure DevOps pipeline ID

Example Request

curl "https://api.deploybrief.com/api/briefs?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "items": [
    {
      "id": "brief-abc-123",
      "pipelineName": "api-production-deploy",
      "buildNumber": "2024.12.13.1",
      "environment": "Production",
      "createdAt": "2024-12-13T10:30:00Z",
      "createdBy": "user@example.com",
      "templateName": "Standard Production Brief"
    }
  ],
  "totalCount": 150,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8
}

GET /api/briefs/{id}

Retrieve a specific deployment brief by ID.

Path Parameters

string

Brief ID

Example Request

curl "https://api.deploybrief.com/api/briefs/brief-abc-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "brief-abc-123",
  "pipelineName": "api-production-deploy",
  "pipelineId": 42,
  "buildNumber": "2024.12.13.1",
  "buildId": 12345,
  "environment": "Production",
  "content": "# Deployment Brief: api-production-deploy\n\n...",
  "format": "markdown",
  "createdAt": "2024-12-13T10:30:00Z",
  "createdBy": "user@example.com",
  "templateId": "template-xyz-789",
  "templateName": "Standard Production Brief",
  "workspaceId": "org-123",
  "metadata": {
    "workItemsCount": 5,
    "commitsCount": 12,
    "testsTotal": 150,
    "testsPassed": 148
  }
}

POST /api/briefs/generate

Generate a new deployment brief.

Request Body

Field	Type	Required	Description
connectionId	string	Yes	Azure DevOps connection ID
project	string	Yes	Azure DevOps project name
pipelineId	integer	Yes	Pipeline ID
buildId	integer	Yes	Build/run ID
templateId	string	No	Template ID (uses default if omitted)

Example Request

curl -X POST "https://api.deploybrief.com/api/briefs/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "conn-123",
    "project": "MyProject",
    "pipelineId": 42,
    "buildId": 12345,
    "templateId": "template-xyz-789"
  }''

Example Response

{
  "id": "brief-new-456",
  "status": "success",
  "message": "Brief generated successfully",
  "briefUrl": "/app/briefs/brief-new-456"
}

POST /api/briefs/generate-from-preset

Generate a brief using a saved preset.

Request Body

Field	Type	Required	Description
presetId	string	Yes	Preset ID
buildId	integer	Yes	Build/run ID

Example Request

curl -X POST "https://api.deploybrief.com/api/briefs/generate-from-preset" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "preset-abc-123",
    "buildId": 12345
  }''

DELETE /api/briefs/{id}

Delete a deployment brief.

Path Parameters

string

Brief ID

Example Request

curl -X DELETE "https://api.deploybrief.com/api/briefs/brief-abc-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "message": "Brief deleted successfully"
}

Rate Limits

API requests are rate limited to prevent abuse:

Read operations (GET): 100 requests per minute
Write operations (POST, DELETE): 20 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1702468800

Error Handling

API errors return a consistent format:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Build ID is required",
    "details": {
      "field": "buildId",
      "reason": "missing"
    }
  }
}

Common Error Codes

INVALID_API_KEY - API key is invalid or expired
INSUFFICIENT_PERMISSIONS - API key lacks required scope
INVALID_PARAMETER - Request parameter is invalid
RESOURCE_NOT_FOUND - Requested resource doesn't exist
RATE_LIMIT_EXCEEDED - Too many requests

Next Steps

→ Create API keys for authentication
→ View CI/CD examples using the API
→ Troubleshoot common issues