Sites API

Manage sites through the DCS portal API.

Overview

The Sites API provides endpoints for:

• Listing and retrieving sites
• Managing site settings
• Accessing site statistics

Authentication Required

All Sites API endpoints require authentication. See Authentication.

Endpoints

List Sites

Get all sites the user has access to:

GET /api/sites

Query Parameters

Parameter	Type	Description
companyId	string	Filter by company
status	string	Filter by status: active, pending, archived
limit	number	Max results (default: 50)
offset	number	Pagination offset

Response

{
  "sites": [
    {
      "id": "site_abc123",
      "slug": "acme-corp",
      "name": "Acme Corporation",
      "url": "https://www.acmecorp.com",
      "status": "active",
      "company": {
        "id": "comp_xyz789",
        "name": "Acme Inc"
      },
      "framework": "vitepress",
      "currentVersion": "1.4.2",
      "devVersion": "1.5.0",
      "lastDeployed": "2024-01-15T10:30:00Z",
      "createdAt": "2023-06-01T00:00:00Z"
    }
  ],
  "total": 15,
  "limit": 50,
  "offset": 0
}

Get Site

Get details for a specific site:

GET /api/sites/{siteId}

Response

{
  "id": "site_abc123",
  "slug": "acme-corp",
  "name": "Acme Corporation",
  "description": "Corporate website",
  "url": "https://www.acmecorp.com",
  "devUrl": "https://dev.acmecorp.com",
  "status": "active",
  "company": {
    "id": "comp_xyz789",
    "name": "Acme Inc"
  },
  "repository": {
    "owner": "acme-inc",
    "name": "website",
    "defaultBranch": "main",
    "releaseBranch": "release/1.5.0"
  },
  "framework": {
    "type": "vitepress",
    "version": "1.4.0"
  },
  "versions": {
    "current": "1.4.2",
    "development": "1.5.0"
  },
  "features": {
    "textOverrides": true,
    "seoManagement": true,
    "blogEnabled": true,
    "copilotEnabled": true
  },
  "statistics": {
    "pageViews": 12500,
    "textOverrides": 45,
    "pendingRequests": 3
  },
  "lastDeployed": "2024-01-15T10:30:00Z",
  "createdAt": "2023-06-01T00:00:00Z"
}

Update Site

Update site settings:

PATCH /api/sites/{siteId}

Request Body

{
  "name": "Acme Corp Website",
  "description": "Updated description",
  "url": "https://www.acme.com",
  "features": {
    "blogEnabled": true
  }
}

Response

{
  "success": true,
  "site": {
    "id": "site_abc123",
    "name": "Acme Corp Website",
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Get Site Statistics

GET /api/sites/{siteId}/stats

Query Parameters

Parameter	Type	Description
period	string	day, week, month, year
startDate	string	ISO date
endDate	string	ISO date

Response

{
  "siteId": "site_abc123",
  "period": "month",
  "pageViews": {
    "total": 12500,
    "unique": 8700,
    "byPage": [
      { "path": "/", "views": 5200 },
      { "path": "/about", "views": 2100 },
      { "path": "/blog", "views": 1800 }
    ]
  },
  "content": {
    "textOverrides": 45,
    "seoUpdates": 12,
    "blogPosts": 8
  },
  "development": {
    "requestsCreated": 15,
    "requestsCompleted": 12,
    "deployments": 8
  }
}

Get Site Pages

List all pages for a site:

GET /api/sites/{siteId}/pages

Response

{
  "pages": [
    {
      "slug": "home",
      "path": "/",
      "title": "Home",
      "type": "static",
      "textKeyCount": 12,
      "lastUpdated": "2024-01-15T10:00:00Z"
    },
    {
      "slug": "about",
      "path": "/about",
      "title": "About Us",
      "type": "static",
      "textKeyCount": 8,
      "lastUpdated": "2024-01-10T14:30:00Z"
    }
  ],
  "total": 15
}

Get Site Versions

List version history:

GET /api/sites/{siteId}/versions

Response

{
  "versions": [
    {
      "version": "1.4.2",
      "status": "production",
      "deployedAt": "2024-01-15T10:30:00Z",
      "commitSha": "abc123def",
      "releaseNotes": "Bug fixes and performance improvements"
    },
    {
      "version": "1.5.0",
      "status": "development",
      "branch": "release/1.5.0",
      "changes": 5,
      "createdAt": "2024-01-10T00:00:00Z"
    }
  ]
}

Site Settings

Get Settings

GET /api/sites/{siteId}/settings

Response

{
  "general": {
    "name": "Acme Corporation",
    "description": "Corporate website",
    "timezone": "America/New_York"
  },
  "deployment": {
    "provider": "azure-swa",
    "autoDeployDev": true,
    "requireApproval": true
  },
  "notifications": {
    "email": true,
    "slack": false,
    "webhookUrl": null
  },
  "features": {
    "textOverrides": true,
    "seoManagement": true,
    "blogEnabled": true,
    "copilotEnabled": true
  }
}

Update Settings

PUT /api/sites/{siteId}/settings

Request Body

{
  "general": {
    "timezone": "America/Los_Angeles"
  },
  "notifications": {
    "slack": true,
    "webhookUrl": "https://hooks.slack.com/..."
  }
}

Error Responses

400 Bad Request

{
  "error": "bad_request",
  "message": "Invalid site settings",
  "details": [
    { "field": "url", "message": "Must be a valid URL" }
  ]
}

403 Forbidden

{
  "error": "forbidden",
  "message": "You do not have access to this site"
}

404 Not Found

{
  "error": "not_found",
  "message": "Site not found"
}

Rate Limits

Endpoint	Rate Limit
GET endpoints	100/minute
POST/PUT/PATCH	30/minute
DELETE	10/minute

Webhooks

Configure webhooks for site events:

{
  "webhookUrl": "https://your-server.com/dcs-webhook",
  "events": [
    "site.deployed",
    "site.updated",
    "request.created",
    "request.completed"
  ]
}

Webhook Payload

{
  "event": "site.deployed",
  "timestamp": "2024-01-15T10:30:00Z",
  "site": {
    "id": "site_abc123",
    "slug": "acme-corp"
  },
  "data": {
    "version": "1.4.2",
    "environment": "production",
    "commitSha": "abc123def"
  }
}

Next Steps

• Authentication — API authentication
• SEO API — SEO management
• Text Content API — Text overrides