Deploy Ingest API

API reference for the deploy ingest endpoint -- send deploy events from your CI/CD pipeline to BlameTrail.

The deploy ingest endpoint receives deploy events from your CI/CD pipeline and records them in BlameTrail for suspect scoring, commit enrichment, and incident correlation.

Endpoint

POST /api/ingest/deploy

Authentication

Authenticate requests using the X-Deploy-Token header. Each token is scoped to a specific service and tenant.

curl -X POST https://blametrail.com/api/ingest/deploy \
  -H "Content-Type: application/json" \
  -H "X-Deploy-Token: dpl_abc123def456" \
  -d '{ "commit_sha": "a1b2c3d" }'

Tokens are generated when you create a service. The plaintext token is shown once -- store it as a secret in your CI/CD system. You can rotate a token from the service detail page, which immediately invalidates the previous token.

Request body

Field	Type	Required	Constraints	Description
`commit_sha`	string	Yes	Max 255 characters	The Git commit SHA that was deployed.
`commit_message`	string	No	--	The head commit message.
`branch`	string	No	--	The branch that was deployed.
`deployed_by`	string	No	--	Who triggered the deploy.
`environment`	string	No	--	Target environment (e.g., `production`, `staging`).
`version`	string	No	--	A version string or tag.
`description`	string	No	--	Free-text description of the deploy.
`url`	string	No	Max 2048 characters	Link to the deploy in your CI/CD system.
`commits`	array	No	Max 100 items	Array of commits included in the deploy.

Commits array

Each item in the commits array has the following shape:

Field	Type	Required	Description
`sha`	string	Yes	The commit SHA.
`message`	string	No	The commit message.
`author`	string	No	The commit author.
`timestamp`	string	No	ISO 8601 timestamp of the commit.

Request limits

Limit	Value
Body size	100 KB maximum. Requests exceeding this limit are rejected with `413` before any processing occurs.
Rate limit (production)	60 requests per minute per IP.
Rate limit (test endpoint)	10 requests per minute per IP.

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`.
`X-Deploy-Token`	Yes	The deploy webhook token for the target service.
`X-Idempotency-Key`	No	A unique key for deduplication. If a request with the same idempotency key and token has already been processed, the endpoint returns a `200` with `status: "duplicate"` instead of creating a new deploy.

Responses

Success (200)

{
  "status": "accepted",
  "deploy_id": "d8f5a2b1-3c4e-4f6a-8b9c-1d2e3f4a5b6c"
}

Duplicate (200)

Returned when the X-Idempotency-Key matches a previously processed request:

{
  "status": "duplicate",
  "deploy_id": "d8f5a2b1-3c4e-4f6a-8b9c-1d2e3f4a5b6c"
}

Errors

Status	Reason
`400`	Validation failed. The response body includes details about which fields are invalid.
`401`	Invalid or missing `X-Deploy-Token`.
`413`	Request body exceeds the 100 KB limit.
`429`	Rate limit exceeded. Retry after the duration specified in the `Retry-After` header.

Full example

curl -X POST https://blametrail.com/api/ingest/deploy \
  -H "Content-Type: application/json" \
  -H "X-Deploy-Token: dpl_abc123def456" \
  -H "X-Idempotency-Key: deploy-20260321-abcdef" \
  -d '{
    "commit_sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
    "commit_message": "fix: resolve timeout in payment processing",
    "branch": "main",
    "deployed_by": "github-actions",
    "environment": "production",
    "version": "v2.4.1",
    "url": "https://github.com/org/repo/actions/runs/123456",
    "commits": [
      {
        "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
        "message": "fix: resolve timeout in payment processing",
        "author": "[email protected]",
        "timestamp": "2026-03-21T14:30:00Z"
      }
    ]
  }'

CI/CD integration examples

GitHub Actions

- name: Notify BlameTrail
  if: success()
  run: |
    curl -s -X POST "${{ secrets.BLAMETRAIL_URL }}/api/ingest/deploy" \
      -H "Content-Type: application/json" \
      -H "X-Deploy-Token: ${{ secrets.BLAMETRAIL_DEPLOY_TOKEN }}" \
      -d '{
        "commit_sha": "${{ github.sha }}",
        "commit_message": "${{ github.event.head_commit.message }}",
        "branch": "${{ github.ref_name }}",
        "deployed_by": "${{ github.actor }}",
        "environment": "production"
      }'

GitLab CI

notify_blametrail:
  stage: deploy
  script:
    - |
      curl -s -X POST "$BLAMETRAIL_URL/api/ingest/deploy" \
        -H "Content-Type: application/json" \
        -H "X-Deploy-Token: $BLAMETRAIL_DEPLOY_TOKEN" \
        -d "{
          \"commit_sha\": \"$CI_COMMIT_SHA\",
          \"commit_message\": \"$CI_COMMIT_MESSAGE\",
          \"branch\": \"$CI_COMMIT_BRANCH\",
          \"deployed_by\": \"$GITLAB_USER_LOGIN\",
          \"environment\": \"production\"
        }"

Next steps

Webhook Events -- Reference for outbound webhook event payloads.
Deploy Tracking Overview -- Understand how BlameTrail uses deploy data.

On this page