Deployments

Record a deploy from any CI system so Apperio can judge its impact.

When to use it

Call this once a deploy is live, so Apperio can mark it on your charts and judge it an hour later (see Deploys and verdicts). If your host already creates GitHub deployments for the linked repository, Apperio receives those on its own; calling this as well records the deploy twice.

Request

POST

/api/v1/projects/{projectId}/deployments

X-API-Key required. The key must belong to the project in the path.

Terminal

curl -X POST "https://apperioserver.onrender.com/api/v1/projects/your-project-id/deployments" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"environment":"production","release":"2.4.1","sha":"your-commit-sha","deployedBy":"ci"}'

Field	Default	Notes
`environment`	`production`	Use the same name as the SDK’s environment option. Logs from this environment decide the verdict.
`release`	none	The version you deployed. Use the same value as the SDK’s release option.
`sha`	none	The commit you deployed. Shown on the deploy.
`status`	`success`	success or failure. Only successful deploys get a verdict. Any other value counts as success.
`url`	none	Where the deploy can be seen. Shown as a View link.
`description`	none	A line of text shown under the deploy.
`deployedBy`	none	Who or what deployed it.

Every field is optional. The deploy’s time is when Apperio receives the request; you can’t set it.

Don’t send in_progress

The API also accepts in_progress, but there is no way to update a deploy afterwards, so it would never get a verdict. Call the endpoint once, after the deploy has finished.

Response

201, with the recorded deploy:

JSON

{
  "status": "success",
  "data": {
    "_id": "deployment-id",
    "projectId": "your-project-id",
    "kind": "deployment",
    "provider": "api",
    "environment": "production",
    "release": "2.4.1",
    "sha": "your-commit-sha",
    "deployedBy": "ci",
    "status": "success",
    "startedAt": "2026-01-15T12:00:00.000Z",
    "finishedAt": "2026-01-15T12:00:00.000Z",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z",
    "__v": 0
  }
}

403 with API key does not belong to this project: the project ID in the path isn’t the key’s project.
400: the project ID isn’t a valid ID.

GitHub Actions

Add a step after your deploy step. Store the key as a secret and the project ID as a variable in the repository settings:

.github/workflows/deploy.yml

- name: Record deploy in Apperio
  if: success()
  env:
    APPERIO_API_KEY: ${{ secrets.APPERIO_API_KEY }}
    APPERIO_PROJECT_ID: ${{ vars.APPERIO_PROJECT_ID }}
  run: |
    curl -fsS -X POST "https://apperioserver.onrender.com/api/v1/projects/$APPERIO_PROJECT_ID/deployments" \
      -H "X-API-Key: $APPERIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d "{\"environment\":\"production\",\"release\":\"$GITHUB_SHA\",\"sha\":\"$GITHUB_SHA\",\"deployedBy\":\"$GITHUB_ACTOR\"}"

-f makes the step fail if Apperio refuses the request, so a wrong key doesn’t go unnoticed. Use continue-on-error: true on the step if a failure to record the deploy shouldn’t fail the workflow.

Other CI systems

Any system that can run curl after a deploy works the same way: send the key in X-API-Key and describe the deploy in the JSON body. Keep the key in the system’s secret store, not in the repository.