API Documentation

Integrate Dplyd into your CI/CD pipeline with a single HTTP request. Post deployments to the global feed, track your shipping history, and show off your velocity with live badges.

Authentication

Authenticate your requests by including your API token in the Authorization header. You can generate or roll your token from your profile settings.

Header Format

Authorization: Bearer YOUR_API_TOKEN

Endpoints

POST /api

Create a new deployment announcement. This will appear on the global feed and your profile.

Parameters

Name	Type	Description
message	string	The text content of your deployment announcement. Supports emoji.
url	string	Optional. A link to the commit, PR, or release notes.

Request

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"message": "Deployed v1.2.3", "url": "https://example.com"}' \
  https://api.dplyd.com/api

Response

JSON

{
  "id": 123,
  "message": "Deployed v1.2.3",
  "url": "https://example.com",
  "deployed_at": "2025-04-06T09:30:00Z",
  "user": {
    "id": 42,
    "name": "Jane Smith"
  },
  "status": "success"
}

Error Responses

Authentication Error

{
  "error": "Unauthorized"
}

Validation Error

{
  "error": "validation_error",
  "message": "Validation failed",
  "details": { "message": ["can't be blank"] }
}

Deployment Badges

Live & Uncached

Show off your deployment frequency on your README, documentation, or status page. Badges update instantly when you deploy.

Status Colors

Fresh

≤ 3 hours

Warm

3h - 24h

Active

1d - 7d

Quiet

7d - 30d

Stale

> 30 days

Inactive

No deploys

Standard

Default

Markdown

[![Latest Deploy](https://api.dplyd.com/badge/USERNAME.svg)](https://api.dplyd.com/USERNAME)

Square

?style=square

Markdown

[![Latest Deploy](https://api.dplyd.com/badge/USERNAME.svg?style=square)](https://api.dplyd.com/USERNAME)

Dot

?style=dot

HTML

<img src="https://api.dplyd.com/badge/USERNAME.svg?style=dot" ... />

Filtered

?url=domain.com

Example for "example.com"

Markdown

[![Latest Deploy](https://api.dplyd.com/badge/USERNAME.svg?url=example.com)](...)

Quick Start Recipes

GitHub Actions

- name: Post deploy to Dplyd
  run: |
    curl -X POST https://api.dplyd.com/api \
      -H "Authorization: Bearer ${{ secrets.DPLYD_TOKEN }}" \
      -d "message=Deploy $GITHUB_SHA" \
      -d "url=https://github.com/${{ github.repository }}/commit/$GITHUB_SHA"

Bash Script

#!/usr/bin/env bash
set -euo pipefail
: "${DPLYD_TOKEN?Set DPLYD_TOKEN}"
MESSAGE=${1:-"Deployed $(date -u +%Y-%m-%dT%H:%M:%SZ)"}
URL=${2:-""}
curl -s -X POST https://api.dplyd.com/api \
  -H "Authorization: Bearer ${DPLYD_TOKEN}" \
  -d "message=${MESSAGE}" ${URL:+ -d "url=${URL}"} | jq .

Node.js

import fetch from "node-fetch";
const res = await fetch("https://api.dplyd.com/api", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.DPLYD_TOKEN },
  body: new URLSearchParams({ message: "Deploy from Node", url: "https://example.com" })
});
console.log(await res.json());