CodeCloud: REST API Documentation for a CI/CD Platform

Simulated project — cloud-based build automation tool

A complete API documentation set for a fictional CI/CD tool, written for developers integrating build automation into their own pipelines. The goal was production-level clarity: a developer should be able to trigger their first build without opening a support ticket.

Audience: mid-level developers and DevOps engineers integrating build automation, most of them evaluating the API for the first time.

Contents

1. The problem

2. Approach

3. What I'd validate

4. Documentation sample: core endpoints

5. Documentation sample: webhooks

6. Documentation sample: SDK README

The problem

API docs usually fail in one of two ways: too sparse to actually integrate against, or so exhaustive that the one endpoint a developer needs is buried in forty they don't. I scoped this to the three endpoints that cover the core workflow (start a build, check its status, clear the cache) and gave each one full request and response examples, rather than documenting every theoretical parameter combination.

Approach

Authentication first: OAuth 2.0 setup is the first thing in the docs, not an appendix, since nothing else works until this is right.

Every endpoint gets three things: a plain-language description of what it does, a copy-pasteable request example, and the exact response shape, including error responses.

Webhooks section built around the developer's actual task: subscribing to build events, not just listing the event types. Includes a payload example and a troubleshooting note (use webhook.site to capture payloads before wiring up a real endpoint).

SDK README written to get a developer from install to first successful call in under five lines of code, matching the pattern of Node.js SDK docs developers are already used to.

What I'd validate

• Time from reading the docs to a developer's first successful /build/start call

• Whether webhook setup support tickets reference a specific section of the docs (signals a gap) or none at all (signals the docs are being skipped)

• Rate limit and pagination comprehension, tested by asking a developer to predict what happens on the 501st request in a minute

Documentation sample: core endpoints

POST /build/start — trigger a new build pipeline

// Request
{
  "repo": "my-org/frontend",
  "branch": "main",
  "env": { "NODE_ENV": "production" }
}

// Response (201 Created)
{
  "build_id": "12345678",
  "status": "queued",
  "url": "https://codecloud.io/builds/12345678"
}

// Request
{
  "repo": "my-org/frontend",
  "branch": "main",
  "env": { "NODE_ENV": "production" }
}

// Response (201 Created)
{
  "build_id": "12345678",
  "status": "queued",
  "url": "https://codecloud.io/builds/12345678"
}

// Request
{
  "repo": "my-org/frontend",
  "branch": "main",
  "env": { "NODE_ENV": "production" }
}

// Response (201 Created)
{
  "build_id": "12345678",
  "status": "queued",
  "url": "https://codecloud.io/builds/12345678"
}

curl -X POST https://api.codecloud.io/build/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "my-org/frontend", "branch": "main"}'

curl -X POST https://api.codecloud.io/build/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "my-org/frontend", "branch": "main"}'

curl -X POST https://api.codecloud.io/build/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "my-org/frontend", "branch": "main"}'

GET /build/status?build_id=12345678 — check the status of a build

// Response
{
  "build_id": "12345678",
  "status": "success",
  "duration": "2m 14s",
  "committed_by": "dev@example.com"
}

// Response
{
  "build_id": "12345678",
  "status": "success",
  "duration": "2m 14s",
  "committed_by": "dev@example.com"
}

// Response
{
  "build_id": "12345678",
  "status": "success",
  "duration": "2m 14s",
  "committed_by": "dev@example.com"
}

DELETE /cache — clear the build cache for a project

// Request
{
  "repo": "my-org/frontend",
  "scope": "branch",
  "target": "main"
}

// Response
{
  "message": "Cache cleared successfully."
}

// Request
{
  "repo": "my-org/frontend",
  "scope": "branch",
  "target": "main"
}

// Response
{
  "message": "Cache cleared successfully."
}

// Request
{
  "repo": "my-org/frontend",
  "scope": "branch",
  "target": "main"
}

// Response
{
  "message": "Cache cleared successfully."
}

Rate limits

// Rate limit response
{
  "error": "rate_limit_exceeded",
  "retry_after": 15
}

// Rate limit response
{
  "error": "rate_limit_exceeded",
  "retry_after": 15
}

// Rate limit response
{
  "error": "rate_limit_exceeded",
  "retry_after": 15
}

Pagination

Documentation sample: webhooks

Available events: build.completed, build.failed, cache.cleared

// Payload example
{
  "event": "build.completed",
  "build_id": "12345678",
  "status": "success",
  "timestamp": "2025-07-30T12:30:00Z"
}

// Payload example
{
  "event": "build.completed",
  "build_id": "12345678",
  "status": "success",
  "timestamp": "2025-07-30T12:30:00Z"
}

// Payload example
{
  "event": "build.completed",
  "build_id": "12345678",
  "status": "success",
  "timestamp": "2025-07-30T12:30:00Z"
}

Setup:

1. Go to Project Settings → Webhooks

2. Add your endpoint URL

3. Choose which events to subscribe to

4. Test with a sample payload

Troubleshooting tips: use webhook.site to capture payloads before wiring up a real endpoint, ensure your endpoint returns a 2XX status code, and log failures for debugging.

Documentation sample: SDK README

OAuth 2.0 authorization

POST /oauth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_secret",
  "grant_type": "authorization_code",
  "code": "abc123"
}

POST /oauth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_secret",
  "grant_type": "authorization_code",
  "code": "abc123"
}

POST /oauth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_secret",
  "grant_type": "authorization_code",
  "code": "abc123"
}